Skip to content

fix(flow-runner): honor a screen field's visibleWhen — render and validation (framework#3528) - #2899

Merged
os-zhuang merged 1 commit into
mainfrom
claude/screen-field-visible-when-3528
Jul 28, 2026
Merged

fix(flow-runner): honor a screen field's visibleWhen — render and validation (framework#3528)#2899
os-zhuang merged 1 commit into
mainfrom
claude/screen-field-visible-when-3528

Conversation

@os-zhuang

@os-zhuang os-zhuang commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Console half of framework#3528. Server half: objectstack#3771 (puts the predicate on the wire — this PR is inert without it).

Why #3528 was still open

The issue was triaged as the object-form lazy-chunk teardown fixed in #2830. That mechanism cannot fire on the reporter's app: HotCRM's lead_conversion and schedule_followup are flat-field screens, and the flat path (ScreenView.FieldInput) renders statically-imported Input/Select/Checkbox/Textarea — nothing suspends. The refreshAfter race was already guarded at the 16.1.0 pin cf2d56e.

So I reproduced the reporter's path in Chromium against a live HotCRM dev server, on both the console shipped with @objectstack/* 16.1.0 and current main (HMR console pointed at the same backend). Identical:

→ POST /api/v1/automation/lead_conversion/trigger   200 {status: paused, screen}
   rendered field labels: ["Create Opportunity? *", "Opportunity Name *", "Opportunity Amount"]
   click Submit (checkbox untouched)
→ (nothing)
RESUME calls: 0     dialog still open: true

The defect

FlowRunner.submit() enforced required over screenFields(screen) — the whole declared list — while ScreenView rendered that same full list because visibleWhen never arrived. HotCRM's screen is the shape that turns this fatal:

{ name: 'createOpportunity', type: 'boolean', required: true },
{ name: 'opportunityName',   type: 'text', required: true,
  visibleWhen: 'createOpportunity == true' },

Leave the checkbox unticked and Submit blocks on opportunityName — a field that should not be on screen at all — and returns before any fetch. Zero requests, run paused forever.

Render and enforcement disagreeing is the whole bug, so they now come from one call.

Changes

  • visibleScreenFields(screen, values) — the single source of truth for what is on screen. ScreenView renders from it; FlowRunner.submit() validates from it.
  • ScreenFieldSpec.visibleWhen — mirrors the contract added in objectstack#3771.
  • Predicates are bare CEL over the screen's own field names, evaluated through evalFieldPredicate (the canonical @objectstack/formula engine — the same verdict the server reaches for field rules). Values bind both bare and under record., so either spelling resolves.
  • Declared fields are seeded before evaluation. This one is not obvious: an untouched checkbox holds undefined, and to CEL an unbound name is an unknown identifier — evaluation errors, evalFieldPredicate falls open, and the dependent field stays on screen in exactly the state where it should be hidden. Booleans seed false, everything else null. Seeding only declared names keeps fail-open intact for a genuinely broken predicate.
  • Fail-open on a broken predicate is deliberate and matches resolveFieldRuleState: hiding an input because its predicate has a typo would silently drop data the flow is waiting for.

Screens with no visibleWhen are untouched — covered by a test.

Test plan

  • New FlowRunner.visibleWhen.test.tsx — 6 cases: hidden while false, revealed when true, resumes with a hidden required field empty (the regression), still blocks on a visible required field, fails open on a broken predicate, and a no-predicate screen unchanged.
  • Both halves verified to bite: reverting either the render side or the validation side fails 2 of 6.
  • packages/app-shell/src/views/__tests__ + ScreenPreview65 passed (11 files).
  • pnpm --filter @object-ui/app-shell type-check — clean (0 errors, after building workspace deps).
  • ESLint on changed files: 0 errors (15 pre-existing any warnings in ScreenView's object-form props, untouched).

End-to-end, this branch's console driven against a dev server carrying objectstack#3771 plus the HotCRM authoring fixes:

→ POST .../lead_conversion/trigger              (paused)
   rendered: ["Create Opportunity? *"]           ← conditional fields correctly hidden
   click Submit
→ POST .../runs/run_63d43c4c.../resume  {"inputs":{"createOpportunity":false}}
   toast "Done", dialog closed, 0 server errors  ← flow ran to completion

Follow-up, not in this PR

HotCRM authored the predicate in the wrong dialect ('{createOpportunity} == true', flow {var} interpolation, rather than the bare CEL the key declares). That is an app-side fix; with this PR the wrong dialect fails open — the field renders and stays fillable — rather than dead-ending, which is the correct degradation.

Correction

An earlier revision of this description claimed the blocked-Submit path surfaces no toast, and flagged it as a separate silent-failure defect. That was wrong — a measurement artifact. My probe polled 5s after the click and sonner's error toast lasts ~4s. Polling tightly shows it at ~250ms: "Please fill: What is the next step?, Due Date". submit()'s feedback works; the real signal was always the zero network requests.

🤖 Generated with Claude Code

https://claude.ai/code/session_0122xvfanLmniNbsAPtg5hk3

…alidation (framework#3528)

A paused screen-flow rendered every declared field regardless of its
`visibleWhen` predicate while still enforcing `required` over the full list.
Where a field is optional-by-design but required *when shown*, that dead-ends
the run: Submit blocks on an input the user was never shown, issues zero
network requests, and the flow stays paused.

Reproduced in Chromium against a live HotCRM dev server on both the console
shipped with 16.1.0 and current main — trigger fires, all three lead-conversion
fields render, Submit does nothing, no toast, dialog stuck open.

The predicate never reached the client: the framework declared `visibleWhen` on
the screen node's designer form but dropped it when building the paused payload
(objectstack#3771). This is the consumer half.

- `visibleScreenFields(screen, values)` becomes the single source of truth.
  ScreenView renders from it, FlowRunner.submit() validates from it. Splitting
  render from enforcement is precisely the defect, so they now share one call.
- Predicates are bare CEL over the screen's own field names, evaluated by the
  canonical @objectstack/formula engine — the same verdict the server reaches
  for field rules. Values bind bare and under `record.`.
- Declared fields are seeded before evaluation. An untouched checkbox holds
  `undefined`, which CEL reads as an unknown identifier: the evaluation errors,
  falls open, and leaves the dependent field visible in exactly the state where
  it should be hidden. Booleans seed false, everything else null.
- Fail-open survives for genuinely broken predicates (syntax error, or a name
  that is not a field on this screen) — hiding an input on a typo would
  silently drop data the flow is waiting for.

Both new regression assertions verified to fail with either half reverted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0122xvfanLmniNbsAPtg5hk3
@vercel

vercel Bot commented Jul 28, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectui Ignored Ignored Jul 28, 2026 4:09am

Request Review

@github-actions github-actions Bot added the tests label Jul 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

✅ Console Performance Budget

Metric Value Budget
Main entry (gzip) 27.9 KB 350 KB
Entry file index-Ck169RNc.js
Status PASS

📦 Bundle Size Report

Package Size Gzipped
app-shell (index.js) 8.20KB 2.97KB
app-shell (runtime-config.js) 7.42KB 2.32KB
app-shell (types.js) 0.01KB 0.04KB
app-shell (urlParams.js) 7.57KB 2.97KB
auth (AuthContext.js) 0.31KB 0.24KB
auth (AuthGuard.js) 1.17KB 0.53KB
auth (AuthProvider.js) 22.10KB 4.37KB
auth (AuthShell.js) 3.49KB 1.40KB
auth (ForgotPasswordForm.js) 12.12KB 3.41KB
auth (LoginForm.js) 17.86KB 5.29KB
auth (PreviewBanner.js) 0.90KB 0.50KB
auth (RegisterForm.js) 6.43KB 2.09KB
auth (SocialSignInButtons.js) 9.60KB 3.89KB
auth (UserMenu.js) 3.40KB 1.22KB
auth (auth-gate-events.js) 1.29KB 0.66KB
auth (authStyles.js) 5.04KB 1.72KB
auth (createAuthClient.js) 35.76KB 9.11KB
auth (createAuthenticatedFetch.js) 4.37KB 1.69KB
auth (index.js) 2.17KB 0.96KB
auth (org-roles.js) 5.50KB 2.36KB
auth (phone-identifier.js) 1.11KB 0.66KB
auth (types.js) 0.59KB 0.35KB
auth (useAuth.js) 4.91KB 0.87KB
auth (useIsWorkspaceAdmin.js) 1.61KB 0.85KB
collaboration (CommentThread.js) 18.38KB 4.49KB
collaboration (LiveCursors.js) 3.17KB 1.27KB
collaboration (PresenceAvatars.js) 3.65KB 1.42KB
collaboration (PresenceProvider.js) 2.79KB 1.13KB
collaboration (index.js) 1.25KB 0.53KB
collaboration (useCommentSearch.js) 1.98KB 0.88KB
collaboration (useConflictResolution.js) 7.75KB 1.86KB
collaboration (useMentionNotifications.js) 1.81KB 0.68KB
collaboration (usePresence.js) 6.33KB 1.84KB
collaboration (useRealtimeSubscription.js) 7.91KB 2.01KB
components (index.js) 449.62KB 97.73KB
core (index.js) 2.12KB 0.77KB
create-plugin (index.js) 9.28KB 2.98KB
data-objectstack (index.js) 127.78KB 32.15KB
fields (index.js) 218.37KB 53.54KB
i18n (LocalizationContext.js) 1.76KB 0.96KB
i18n (currency.js) 1.22KB 0.64KB
i18n (i18n.js) 4.32KB 1.77KB
i18n (index.js) 2.46KB 0.96KB
i18n (pickLocalized.js) 1.70KB 0.83KB
i18n (provider.js) 5.37KB 1.72KB
i18n (useObjectLabel.js) 25.17KB 5.80KB
i18n (useSafeTranslation.js) 3.26KB 1.44KB
layout (index.js) 38.45KB 10.67KB
mobile (MobileProvider.js) 0.92KB 0.49KB
mobile (ResponsiveContainer.js) 0.94KB 0.38KB
mobile (breakpoints.js) 1.51KB 0.70KB
mobile (createOfflineDataSource.js) 5.61KB 1.74KB
mobile (index.js) 1.50KB 0.62KB
mobile (offlineQueue.js) 3.91KB 1.35KB
mobile (pwa.js) 0.97KB 0.49KB
mobile (serviceWorker.js) 1.48KB 0.62KB
mobile (serviceWorkerSource.js) 3.41KB 1.48KB
mobile (useBreakpoint.js) 1.54KB 0.65KB
mobile (useGesture.js) 4.42KB 1.27KB
mobile (useOfflineSync.js) 1.99KB 0.72KB
mobile (usePullToRefresh.js) 2.53KB 0.85KB
mobile (useResponsive.js) 0.71KB 0.42KB
mobile (useResponsiveConfig.js) 1.36KB 0.63KB
mobile (useSpecGesture.js) 1.77KB 0.77KB
mobile (useTouchTarget.js) 1.01KB 0.54KB
permissions (MePermissionsProvider.js) 6.84KB 2.42KB
permissions (PermissionContext.js) 0.31KB 0.25KB
permissions (PermissionGuard.js) 0.89KB 0.45KB
permissions (PermissionProvider.js) 3.67KB 1.12KB
permissions (evaluator.js) 4.00KB 1.23KB
permissions (index.js) 0.91KB 0.41KB
permissions (store.js) 0.91KB 0.42KB
permissions (useFieldPermissions.js) 1.28KB 0.52KB
permissions (usePermissions.js) 1.55KB 0.71KB
plugin-ai (index.js) 15.71KB 3.79KB
plugin-calendar (index.js) 44.90KB 12.35KB
plugin-charts (index.js) 57.26KB 16.24KB
plugin-chatbot (index.js) 179.50KB 42.71KB
plugin-dashboard (index.js) 109.60KB 28.33KB
plugin-designer (index.js) 210.56KB 42.56KB
plugin-detail (index.js) 214.86KB 52.39KB
plugin-editor (index.js) 2.46KB 1.10KB
plugin-form (index.js) 103.47KB 25.10KB
plugin-gantt (index.js) 162.26KB 39.53KB
plugin-grid (index.js) 178.13KB 46.73KB
plugin-kanban (index.js) 47.82KB 13.18KB
plugin-list (index.js) 98.64KB 23.33KB
plugin-map (index.js) 16.80KB 5.24KB
plugin-markdown (index.js) 13.65KB 4.67KB
plugin-report (index.js) 37.07KB 9.81KB
plugin-timeline (index.js) 25.03KB 7.11KB
plugin-tree (index.js) 8.36KB 2.81KB
plugin-view (index.js) 85.68KB 20.85KB
providers (DataSourceProvider.js) 0.75KB 0.39KB
providers (MetadataProvider.js) 1.37KB 0.59KB
providers (ThemeProvider.js) 1.55KB 0.67KB
providers (UploadProvider.js) 11.71KB 3.53KB
providers (index.js) 0.44KB 0.22KB
providers (types.js) 0.01KB 0.04KB
react-runtime (index.js) 3.19KB 1.38KB
react (LazyPluginLoader.js) 3.77KB 1.33KB
react (SchemaRenderer.js) 18.70KB 6.09KB
react (data-invalidation.js) 5.05KB 2.08KB
react (index.js) 1.00KB 0.55KB
sdui-parser (codegen.js) 4.09KB 1.74KB
sdui-parser (index.js) 2.16KB 0.94KB
sdui-parser (parse.js) 10.04KB 2.82KB
sdui-parser (types.js) 0.29KB 0.24KB
sdui-parser (validate.js) 4.69KB 1.48KB
types (ai.js) 0.20KB 0.17KB
types (api-types.js) 0.20KB 0.18KB
types (app.js) 2.87KB 0.99KB
types (base.js) 0.20KB 0.18KB
types (blocks.js) 0.20KB 0.18KB
types (complex.js) 0.20KB 0.18KB
types (crud.js) 0.20KB 0.18KB
types (data-display.js) 0.20KB 0.18KB
types (data-protocol.js) 0.20KB 0.19KB
types (data.js) 0.20KB 0.18KB
types (designer.js) 0.77KB 0.41KB
types (disclosure.js) 0.20KB 0.18KB
types (feedback.js) 0.20KB 0.18KB
types (field-types.js) 0.20KB 0.18KB
types (form.js) 0.20KB 0.18KB
types (index.js) 1.86KB 0.91KB
types (layout.js) 0.20KB 0.18KB
types (managed-by.js) 0.19KB 0.18KB
types (mobile.js) 0.20KB 0.18KB
types (navigation.js) 0.20KB 0.18KB
types (objectql.js) 0.20KB 0.18KB
types (overlay.js) 0.20KB 0.18KB
types (permissions.js) 0.20KB 0.18KB
types (plugin-scope.js) 0.20KB 0.18KB
types (record-components.js) 0.20KB 0.19KB
types (record-semantics.js) 1.28KB 0.67KB
types (registry.js) 0.20KB 0.18KB
types (reports.js) 0.20KB 0.18KB
types (spec-report.js) 5.04KB 1.93KB
types (system-fields.js) 2.39KB 1.17KB
types (theme.js) 0.20KB 0.18KB
types (ui-action.js) 0.75KB 0.46KB
types (views.js) 0.20KB 0.18KB
types (widget.js) 0.20KB 0.18KB

Size Limits

  • ✅ Core packages should be < 50KB gzipped
  • ✅ Component packages should be < 100KB gzipped
  • ⚠️ Plugin packages should be < 150KB gzipped

os-zhuang added a commit to objectstack-ai/objectstack that referenced this pull request Jul 28, 2026
… (#3771)

`visibleWhen` has been on the `screen` node's designer form since #3304 —
declared `xExpression`, documented as bare CEL, offered in Studio — but the
executor dropped it when building the paused payload, so no client ever
received the predicate and none could honour it.

`required` IS honoured, which is what made this fatal rather than cosmetic: a
field that is optional-by-design but required when shown becomes permanently
required once its predicate is dropped, and a runner validating the full field
list then blocks Submit on input the user was never asked for — no resume
request issued, run left paused. Reproduced in a browser against HotCRM on both
the console shipped with 16.1.0 and current objectui main.

- `ScreenFieldSpec.visibleWhen` joins the contract, documented as
  client-evaluated bare CEL, stating that a hidden field must not be enforced
  as required.
- The executor forwards it raw; interpolating here would freeze a predicate the
  client must re-evaluate against values only it can see.
- Tests for the screen wire payload, which had none for this key.
- Documents the flat screen-field shape in the flows guide, which only covered
  the object-form step.

Console half: objectstack-ai/objectui#2899.
@os-zhuang
os-zhuang marked this pull request as ready for review July 28, 2026 05:18
@os-zhuang
os-zhuang merged commit 1bb77aa into main Jul 28, 2026
14 checks passed
@os-zhuang
os-zhuang deleted the claude/screen-field-visible-when-3528 branch July 28, 2026 05:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants